<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<title>user</title>
	</head>
	<body>
		<p><h1>Table of Contents</h1></p>
		<ol style="list-style: none;">
			<li>
				<a href="#Description">Description</a>
			</li>
			<li>
				<a href="#Customization_Metamodel">Customization Metamodel</a>
				<ol style="list-style: none;">
					<li>
						<a href="#customizations">customizations</a>
					</li>
					<li>
						<a href="#customizable_features">customizable features</a>
					</li>
					<li>
						<a href="#customization_override">customization override</a>
						<ol style="list-style: none;">
							<li>
								<a href="#customizing_an_EClass">customizing an EClass</a>
							</li>
							<li>
								<a href="#customizing_a_Facet">customizing a Facet</a>
							</li>
						</ol>
					</li>
					<li>
						<a href="#customizing_structural_features">customizing structural features</a>
					</li>
					<li>
						<a href="#conditional_customization">conditional customization</a>
					</li>
					<li>
						<a href="#customization_cases">customization cases</a>
					</li>
				</ol>
			</li>
			<li>
				<a href="#Example">Example</a>
			</li>
			<li>
				<a href="#Default_Customizations">Default Customizations</a>
				<ol style="list-style: none;">
					<li>
						<a href="#label">label</a>
					</li>
					<li>
						<a href="#image">image</a>
					</li>
					<li>
						<a href="#color">color</a>
					</li>
					<li>
						<a href="#font">font</a>
					</li>
					<li>
						<a href="#overlay">overlay</a>
					</li>
					<li>
						<a href="#obtaining_customization_properties">obtaining customization properties</a>
					</li>
				</ol>
			</li>
			<li>
				<a href="#Registration">Registration</a>
			</li>
			<li>
				<a href="#Catalog">Catalog</a>
			</li>
			<li>
				<a href="#Customization_Manager">Customization Manager</a>
			</li>
			<li>
				<a href="#Customized_Providers">Customized Providers</a>
			</li>
		</ol>
		<p>EMF Facet provides a 
			<b>customization</b> component, that can be used to define the appearance of model elements when viewed in an editor or view that supports this customization mechanism.
		</p>
		<h2 id="Description">Description</h2>
		<p>A customization is defined in a model that conforms to the EMF Facet customization metamodel. This model is saved in a file with the ".custom" file extension.</p>
		<h2 id="Customization_Metamodel">Customization Metamodel</h2>
		<h3 id="customizations">customizations</h3>
		<p>A 
			<b>Customization</b> is a 
			<b>FacetSet</b>: 
		</p>
		<p>
			<img border="0" src="../img/CustomizationMetaclass.png"/>
		</p>
		<p>A 
			<b>Customization</b> can contain customizations for Ecore metaclasses (
			<b>EClassCustomization</b>), or Facets (
			<b>FacetCustomization</b>). Both 
			<b>EClassCustomization</b> and 
			<b>FacetCustomization</b> are Facets.
		</p>
		<p>The 
			<b>extendedMetaclass</b> of an 
			<b>EClassCustomization</b> is the EClass whose instances will be customized.
		</p>
		<p>The 
			<b>extendedFacet</b> of an 
			<b>EClassCustomization</b> or 
			<b>FacetCustomization</b> is the Facet that defines the customizable features (label, color, etc.) that will be customized.
		</p>
		<p>In case of facet customization, the 
			<b>customizedFacet</b> of a 
			<b>FacetCustomization</b> is the Facet for which model elements that conform to this Facet will be customized.
		</p>
		<p>
			<img border="0" src="../img/EClassAndFacetCustomizationMetaclasses.png"/>
		</p>
		<h3 id="customizable_features">customizable features</h3>
		<p>Customizable features are defined in Facets as FacetOperations. For example, this FacetSet defines basic customizable features such as label, icon, etc.: <code>platform:/plugin/org.eclipse.papyrus.emf.facet.custom.ui/resources/customproperties.efacet</code></p>
		<p>The following instance diagram shows how a Facet named 
			<b>CustomizedEObject</b> is defined in 
			<i>customproperties.efacet</i>. Its 
			<b>extendedMetaclass</b> is 
			<b>EObject</b>, so it can be used to customize any model element. It contains 
			<b>FacetOperations</b> (of which only two are represented here). These FacetOperations define the customizable features: here the 
			<b>label</b> and 
			<b>image</b> for a model element. The type of each of these FacetOperations is the customized feature's type : an 
			<b>EString</b> for the label and an 
			<b>Image</b> for the image. 
		</p>
		<p>
			<img border="0" src="../img/CustomizedEObject.png"/>
		</p>
		<p>The operation is called each time the value of its customization is needed. For example, when displaying a model element in a viewer, we will need its label. So the 
			<b>label</b> operation will be called on the model element for which the label is needed.
		</p>
		<h3 id="customization_override">customization override</h3>
		<p>A FacetOperation that defines a customizable feature such as label, icon, color, font, etc. can be compared to a virtual method: it is meant to be overridden in extending Facets in order to provide a specific customization.</p>
		<p>To understand this override mechanism, remember that a 
			<b>EClassCustomization</b> and 
			<b>FacetCustomization</b> are 
			<b>Facets</b> (the 
			<b>EClassCustomization</b> and 
			<b>FacetCustomization</b> metaclasses extend the 
			<b>Facet</b> metaclass).
		</p>
		<h4 id="customizing_an_EClass">customizing an EClass</h4>
		<p>To create a customization for instances of an 
			<b>EClass</b>: 
		</p>
		<ul>
			<li>create an 
				<b>EClassCustomization</b>
			</li>
			<li>the new 
				<b>EClassCustomization</b>'s 
				<b>extendedMetaclass</b> is the 
				<b>EClass</b> whose instances you want to customize
			</li>
			<li>the new 
				<b>EClassCustomization</b>'s 
				<b>extendedFacet</b> is the Facet that defines the customizable feature you want to customize (i.e. the label, color, font,...)
			</li>
			<li>you create a 
				<b>FacetOperation</b> in your 
				<b>EClassCustomization</b> for each customizable feature you want to customize
			</li>
			<li>each of these 
				<b>FacetOperations</b> 
				<b>overrides</b> the 
				<b>FacetOperation</b> (from the 
				<b>extendedFacet</b>) corresponding to the customizable feature you want to customize
			</li>
			<li>the overriding FacetOperation and the overridden FacetOperation must have the same type</li>
			<li>finally, you provide an implementation for your overriding 
				<b>FacetOperation</b>, by the means of a 
				<b>Query</b> that will return the value of the customization when this Query is evaluated on an instance of the 
				<b>extendedMetaclass</b>
			</li>
		</ul>
		<p>In the following example, we customize the label of instances of the 
			<b>Writer</b> metaclass from a library metamodel (defined in 
			<i>library.ecore</i>). For this, we create an 
			<b>EClassCustomization</b> which extends the 
			<b>CustomizedEObject</b> Facet. This 
			<b>CustomizedEObject</b> Facet provides the customizable feature 
			<b>label</b> which we want to customize. So, we create a FacetOperation (in our EClassCustomization) which overrides the 
			<b>label</b> FacetOperation (in CustomizedEObject). Finally, we choose to provide the label using a Java query, so we create a JavaQuery under our label FacetOperation's 
			<b>query</b> reference. We set this JavaQuery's 
			<b>implementationClassName</b> to the full qualified name of a Java class that implements the query and returns the label corresponding to a Writer instance passed as a 
			<b>source</b> to this query.
		</p>
		<p>
			<img border="0" src="../img/customizationWithOverride.png"/>
		</p>
		<h4 id="customizing_a_Facet">customizing a Facet</h4>
		<p>To create a customization for model elements that conform to a 
			<b>Facet</b>: 
		</p>
		<ul>
			<li>create a 
				<b>FacetCustomization</b>
			</li>
			<li>the new 
				<b>FacetCustomization</b>'s 
				<b>extendedFacet</b> is the 
				<b>Facet</b> whose conforming elements you want to customize
			</li>
			<li>you create a 
				<b>FacetOperation</b> in your 
				<b>FacetCustomization</b> for each customizable feature (label, font, color, etc.) you want to customize
			</li>
			<li>each of these 
				<b>FacetOperations</b> 
				<b>overrides</b> the 
				<b>FacetOperation</b> corresponding to the customizable feature you want to customize
			</li>
			<li>the overriding FacetOperation and the overridden FacetOperation must have the same type</li>
			<li>finally, you provide an implementation for your overriding 
				<b>FacetOperation</b>, by the means of a 
				<b>Query</b> that will return the value of the customization when this Query is evaluated on a model element that conforms to the 
				<b>extendedFacet</b>
			</li>
		</ul>
		<p>In the following example, we want to add an overlay icon on elements that conform to the 
			<b>UnproductiveWriter</b> metaclass from the library FacetSet (defined in 
			<i>library.efacet</i>). For this, we create an 
			<b>FacetCustomization</b> which extends the 
			<b>UnproductiveWriter</b> Facet. We create a FacetOperation (in our FacetCustomization) which overrides the 
			<b>bottomRightOverlay</b> FacetOperation that allows adding an overlay icon in the bottom right corner of an element's main icon. Finally, we provide the overlay icon using a query. This query will be evaluated with instances of 
			<b>Writer</b> that conform to the 
			<b>UnproductiveWriter</b> Facet, and will return the overlay icon.
		</p>
		<p>
			<img border="0" src="../img/customizingFacetWithOverride.png"/>
		</p>
		<h3 id="customizing_structural_features">customizing structural features</h3>
		<p>Each FacetOperation that defines a customizable feature has a parameter named 
			<b>eStructuralFeature</b>. This parameter is useful for customizing the structural feature corresponding to a single model element. For example, in the following screenshot, a 
			<b>Library</b> model element contains 
			<b>Writers</b> through a structural feature named 
			<b>writers</b>. If we want to customize this 
			<b>writers</b> structural feature in the context of its parent 
			<b>Library</b>, then we need both the 
			<b>Library</b> model element and the 
			<b>writers</b> feature. In this case, the FacetOperation would be called on the 
			<b>Library</b> model element, and the value of the 
			<b>eStructuralFeature</b> parameter would be the 
			<b>writers</b> feature.
		</p>
		<p>
			<img border="0" src="../img/LibraryModelInModelBrowser.png"/>
		</p>
		<h3 id="conditional_customization">conditional customization</h3>
		<p>To specify that a customization should only be applied to elements that satisfy certain criteria, you have two choices:</p>
		<ul>
			<li>Either customize a Facet that applies to elements you want to customize. This is the preferred way.</li>
			<li>Customize an EClass and set the 
				<b>conformanceTypedElement</b> of the customization to a boolean attribute (
				<b>EAttribute</b> or 
				<b>FacetAttribute</b>) that returns whether the customization should be applied on the attribute's source element.
			</li>
		</ul>
		<h3 id="customization_cases">customization cases</h3>
		<p>To handle several cases in a customization (to return different values for a single customized feature depending on boolean conditions), you can implement the customized 
			<b>FacetOperation</b> with an 
			<b>ETypedElementSwitchQuery</b>. This type of query returns the value corresponding to the first of its cases that evaluates to 
			<b>true</b>.
		</p>
		<p>
			<img border="0" src="../img/ETypedElementSwitchQuery.png"/>
		</p>
		<h2 id="Example">Example</h2>
		<p>Since there is no dedicated UI tooling as yet for editing customizations, you will have to use either a generic model editor or write the XMI by hand for now. Here is an example of a customization model in the XMI format. This example defines a customization for the 
			<b>Writer</b> metaclass, that customizes the label for 
			<b>Writer</b> model elements. And a second customization that customizes the 
			<b>UnproductiveWriter</b> Facet, to add an overlay to the icon of model elements that conform to the 
			<b>UnproductiveWriter</b> Facet.
		</p>
		<pre>
&lt;custom:Customization
	xmi:version="2.0"
	xmlns:xmi="http://www.omg.org/XMI"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:custom="http://www.eclipse.org/papyrus/emf/facet/custom/0.2.incubation/custom"
	xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore"
	xmlns:efacet="http://www.eclipse.org/papyrus/emf/facet/efacet/0.2.incubation/efacet"
	xmlns:javaQuery2="http://www.eclipse.org/papyrus/emf/facet/query/java/0.2.incubation"
	name="org.eclipse.papyrus.emf.facet.efacet.examples.library.core.custom"&gt;

  &lt;eClassifiers xsi:type="custom:EClassCustomization"&gt;
    &lt;extendedMetaclass href="http://www.eclipse.org/papyrus/emf/facet/examples/library/0.2.incubation/library#//Writer"/&gt;
    &lt;extendedFacets href="platform:/plugin/org.eclipse.papyrus.emf.facet.custom.ui/resources/customproperties.efacet#//CustomizedEObject"/&gt;
    &lt;facetOperations xsi:type="efacet:FacetOperation" name="label" lowerBound="1"&gt;
      &lt;eType xsi:type="ecore:EDataType" href="http://www.eclipse.org/emf/2002/Ecore#//EString"/&gt;
      &lt;query xsi:type="javaQuery2:JavaQuery" implementationClassName="org.eclipse.papyrus.emf.facet.efacet.examples.library.core.internal.queries.WriterLabel"/&gt;
      &lt;override xsi:type="efacet:FacetOperation" href="platform:/plugin/org.eclipse.papyrus.emf.facet.custom.ui/resources/customproperties.efacet#//CustomizedEObject/label"/&gt;
      &lt;eParameters xsi:type="ecore:EParameter" name="eStructuralFeature"&gt;
      	&lt;eType xsi:type="ecore:EDataType" href="http://www.eclipse.org/emf/2002/Ecore#//EStructuralFeature"/&gt;
      &lt;/eParameters&gt;
    &lt;/facetOperations&gt;
  &lt;/eClassifiers&gt;

  &lt;eClassifiers xsi:type="custom:FacetCustomization"&gt;
    &lt;extendedFacets href="platform:/plugin/org.eclipse.papyrus.emf.facet.efacet.examples.library.core/library.efacet#//writer/UnproductiveWriter"/&gt;
    &lt;facetOperations xsi:type="efacet:FacetOperation" name="bottomRightOverlay" lowerBound="1"&gt;
      &lt;eType xsi:type="ecore:EDataType" href="http://www.eclipse.org/papyrus/emf/facet/custom/0.2.incubation/custom_primitive_types#//Image"/&gt;
      &lt;query xsi:type="javaQuery2:JavaQuery" implementationClassName="org.eclipse.papyrus.emf.facet.efacet.examples.library.core.internal.queries.UnproductiveWriterOverlay"/&gt;
      &lt;override xsi:type="efacet:FacetOperation" href="platform:/plugin/org.eclipse.papyrus.emf.facet.custom.ui/resources/customproperties.efacet#//CustomizedEObject/bottomRightOverlay"/&gt;
      &lt;eParameters xsi:type="ecore:EParameter" name="eStructuralFeature"&gt;
      	&lt;eType xsi:type="ecore:EDataType" href="http://www.eclipse.org/emf/2002/Ecore#//EStructuralFeature"/&gt;
      &lt;/eParameters&gt;
    &lt;/facetOperations&gt;
  &lt;/eClassifiers&gt;
&lt;/custom:Customization&gt;
</pre>
		<h2 id="Default_Customizations">Default Customizations</h2>
		<h3 id="label">label</h3>
		<p>The text displayed for a model element can be customized with the 
			<b>label</b> customization defined on CustomizedEObject.
		</p>
		<h3 id="image">image</h3>
		<p>The icon that appears before the text for a model element can be customized with the 
			<b>image</b> customization defined on CustomizedEObject.
		</p>
		<h3 id="color">color</h3>
		<p>Both the text color (
			<b>foreground</b>) and background color (
			<b>background</b>) can be customized. 
		</p>
		<h3 id="font">font</h3>
		<p>The following font-related properties are defined on CustomizedEObject and can be customized:</p>
		<ul>
			<li>fontName</li>
			<li>fontSize</li>
			<li>isBold</li>
			<li>isItalic</li>
			<li>isUnderlined</li>
			<li>isStruckthrough</li>
		</ul>
		<h3 id="overlay">overlay</h3>
		<p>In addition to the main icon displayed for a model element, up to six additional 
			<i>overlay</i> icons can be displayed in the corners of the main icon. The following image depicts the position of each overlay relative to the main icon:
		</p>
		<table style="text-align: center; border-style: solid; border-width: 2px; border-color: #000">
			<tr>
				<td>
					<img border="0" src="../img/topLeftOverlay.png"/>
				</td>
				<td>
					<img border="0" src="../img/topMiddleOverlay.png"/>
				</td>
				<td>
					<img border="0" src="../img/topRightOverlay.png"/>
				</td>
			</tr>
			<tr>
				<td>topLeftOverlay</td>
				<td>topMiddleOverlay</td>
				<td>topRightOverlay</td>
			</tr>
			<tr>
				<td>
					<img border="0" src="../img/bottomLeftOverlay.png"/>
				</td>
				<td>
					<img border="0" src="../img/bottomMiddleOverlay.png"/>
				</td>
				<td>
					<img border="0" src="../img/bottomRightOverlay.png"/>
				</td>
			</tr>
			<tr>
				<td>bottomLeftOverlay</td>
				<td>bottomMiddleOverlay</td>
				<td>bottomRightOverlay</td>
			</tr>
		</table>
		<p>Overlays should be defined on Facets (using a 
			<b>FacetCustomization</b>). You will get a warning if you define an overlay on an EClass (with 
			<b>EClassCustomization</b>). This warning may be disabled in the preferences, in section 
			<b>Model Validation &gt; Constraints</b> : check or uncheck 
			<b>EMF Facet Custom Model Validation &gt; Avoid EClass Overlay</b>.
		</p>
		<h3 id="obtaining_customization_properties">obtaining customization properties</h3>
		<p>The default customization properties defined in EMF Facet can be obtained from the following set of interfaces:</p>
		<ul>
			<li>IContentPropertiesHandler (instantiate through IContentPropertiesHandlerFactory)</li>
			<li>ISelectionPropertiesHandler (instantiate through ISelectionPropertiesHandlerFactory)</li>
		</ul>
		<h2 id="Registration">Registration</h2>
		<p>To make a customization available at runtime in the customization catalog, you must register it with extension point 
			<b>org.eclipse.papyrus.emf.facet.util.emf.core.modeldeclaration</b>, like this:
		</p>
		<pre>
&lt;extension point="org.eclipse.papyrus.emf.facet.util.emf.core.modeldeclaration"&gt;
  &lt;modeldeclaration file="myCustomization.custom"/&gt;
&lt;/extension&gt;
Also, your ".custom" file must be included in your plug-in's build.properties in order to be available in deployed plug-ins.
</pre>
		<h2 id="Catalog">Catalog</h2>
		<p>Customizations that have been 
			<a href="#Registration">registered</a> are available from the customization catalog.
			For example, if you want to retrieve the list of all registered customizations:
		</p>
		<pre>
ICustomizationCatalogManager customCatalog = ICustomizationCatalogManagerFactory.DEFAULT
    .getOrCreateCustomizationCatalogManager(new ResourceSetImpl());
List&lt;Customization&gt; allCustomizations = customCatalog.getRegisteredCustomizations();
</pre>
		<p>Then you can for example look for a customization with a given name in the previous list:</p>
		<pre>
Customization myCustom = CustomizationUtils.getCustomization(allCustomizations, "MyCustomization");
</pre>
		<h2 id="Customization_Manager">Customization Manager</h2>
		<p>The customization manager is used to manipulate customizations. To obtain an instance of the CustomizationManager, you must ask the customization manager factory:</p>
		<pre>
ICustomizationManager customManager = ICustomizationManagerFactory.DEFAULT.getOrCreateICustomizationManager(resourceSet);
</pre>
		<p>The resourceSet parameter must be the same ResourceSet that was used to instantiate a customization catalog manager in <code>ICustomizationCatalogManagerFactory#getOrCreateCustomizationCatalogManager</code>. </p>
		<p>The customization manager provides these important methods:</p>
		<ul>
			<li>getManagedCustomizations() : returns a modifiable list of customizations managed by this customization manager. For example, to add a customization: <code>customManager.getManagedCustomizations().add(custom);</code></li>
			<li>getCustomValueOf(EObject, FacetOperation, Class) : evaluates a customization property on a given object, and returns the result. The class parameter is used to typecheck the result and return a value of the correct type. For example: <code>Boolean result = customManager.getCustomValueOf(eObject, aBooleanProperty, Boolean.class);</code></li>
		</ul>
		<h2 id="Customized_Providers">Customized Providers</h2>
		<p>You don't always have to interact with the customization manager directly though: when you want to evaluate a standard customization property (label, image, visibility, etc.), you can use a customized label or content provider supplied by EMF Facet:</p>
		<ul>
			<li>ICustomizedLabelProvider (instantiate through ICustomizedLabelProviderFactory or IResolvingCustomizedLabelProviderFactory)</li>
			<li>ICustomizedTreeContentProvider (instantiate through ICustomizedContentProviderFactory)</li>
		</ul>
		<p><font size="-2">
			Copyright &#169; 2012 Mia-Software.
			All rights reserved. This program and the accompanying materials
			are made available under the terms of the Eclipse Public License 2.0
			which accompanies this distribution, and is available at

			<a href="https://www.eclipse.org/legal/epl-2.0/">https://www.eclipse.org/legal/epl-2.0/</a>.
			Contributors: Nicolas Bros (Mia-Software) ; Laurent Pichierri (Soft-Maint) - Bug 375789 - Documentation
</font>
		</p>
	</body>
</html>